<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>aio_read</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_001_131">&nbsp;</a>NAME</h4><blockquote>
aio_read - asynchronous read from a file
(<b>REALTIME</b>)
</blockquote><h4><a name = "tag_000_001_132">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="aio.h.html">aio.h</a>&gt;

int aio_read(struct aiocb *<i>aiocbp</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_001_133">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>aio_read()</i>
function allows the calling process to read
<i>aiocbp-&gt;aio_nbytes</i>
from the file associated with
<i>aiocbp-&gt;aio_fildes</i>
into the buffer pointed to by
<i>aiocbp-&gt;aio_buf</i>.
The function call returns when the read request has been
initiated or queued to the file or device
(even when the data cannot be delivered immediately).
If _POSIX_PRIORITIZED_IO is defined
and prioritized I/O is supported for this file,
then the asynchronous operation is submitted at a priority
equal to the scheduling priority of the process minus
<i>aiocbp-&gt;aio_reqprio</i>.
The
<i>aiocbp</i>
value may be used as an argument to
<i><a href="aio_error.html">aio_error()</a></i>
and
<i><a href="aio_return.html">aio_return()</a></i>
in order to determine the
error status and return status, respectively, of the asynchronous operation
while it is proceeding.
If an error condition is encountered during queuing,
the function call returns
without having initiated or queued the request.
The requested operation takes place at the absolute position in
the file as given by
<i>aio_offset</i>,
as if
<i><a href="lseek.html">lseek()</a></i>
were called immediately prior to the operation with an
<i>offset</i>
equal to
<i>aio_offset</i>
and a
<i>whence</i>
equal to
SEEK_SET .
After a successful call to enqueue an asynchronous I/O operation,
the value of the file offset for the file is unspecified.
<p>
The
<i>aiocbp-&gt;aio_lio_opcode</i>
field is ignored by
<i>aio_read()</i>.
<p>
The
<i>aiocbp</i>
argument points to an
<b>aiocb</b>
structure.
If the buffer pointed to by
<i>aiocbp-&gt;aio_buf</i>
or the control block pointed to by
<i>aiocbp</i>
becomes an illegal address prior to asynchronous I/O completion,
then the behaviour is undefined.
<p>
Simultaneous asynchronous operations using the same
<i>aiocbp</i>
produce undefined results.
<p>
If _POSIX_SYNCHRONIZED_IO is defined
and synchronised I/O is enabled on the file associated with
<i>aiocbp-&gt;aio_fildes</i>,
the behaviour of this function is according to the definitions of
synchronised I/O data integrity completion
and
synchronised I/O file integrity completion.
<p>
For any system action that changes the process memory space
while an asynchronous I/O is outstanding to the address range being changed,
the result of that action is undefined.
<p>
For regular files, no data transfer will occur past the offset maximum
established in the open file description associated with
<i>aiocbp-&gt;aio_fildes</i>.
</blockquote><h4><a name = "tag_000_001_134">&nbsp;</a>RETURN VALUE</h4><blockquote>
The
<i>aio_read()</i>
function returns the value zero to the
calling process if the I/O operation is successfully queued;
otherwise, the function returns the value -1 and sets
<i>errno</i>
to indicate the error.
</blockquote><h4><a name = "tag_000_001_135">&nbsp;</a>ERRORS</h4><blockquote>
The 
<i>aio_read()</i>
function will fail if:
<dl compact>

<dt>[EAGAIN]<dd>
The requested asynchronous I/O operation was not queued
due to system resource limitations.

<dt>[ENOSYS]<dd>
The
<i>aio_read()</i>
function is not supported by this implementation.

</dl>
<p>
Each of the following conditions may be detected synchronously
at the time of the call to
<i>aio_read()</i>,
or asynchronously.
If any of the conditions below are detected synchronously, the
<i>aio_read()</i>
function returns -1 and sets
<i>errno</i>
to the corresponding value.
If any of the conditions below are detected asynchronously,
the return status of the asynchronous operation is set to -1,
and the error status of the asynchronous operation will be
set to the corresponding value.
<dl compact>

<dt>[EBADF]<dd>
The
<i>aiocbp-&gt;aio_fildes</i>
argument is not a valid file descriptor open for reading.

<dt>[EINVAL]<dd>
The file offset value implied by
<i>aiocbp-&gt;aio_offset</i>
would be invalid,
<i>aiocbp-&gt;aio_reqprio</i>
is not a valid value, or
<i>aiocbp-&gt;aio_nbytes</i>
is an invalid value.

</dl>
<p>
In the case that the
<i>aio_read()</i>
successfully queues the I/O operation
but the operation is subsequently canceled or encounters an error,
the return status of the asynchronous operation
is one of the values normally returned by the
<i><a href="read.html">read()</a></i>
function call.
In addition, the error status of the asynchronous operation will
be set to one of the error statuses normally set by the
<i><a href="read.html">read()</a></i>
function call, or one of the following values:
<dl compact>

<dt>[EBADF]<dd>
The
<i>aiocbp-&gt;aio_fildes</i>
argument is not a valid file descriptor open for reading.

<dt>[ECANCELED]<dd>
The requested I/O was canceled before the I/O completed due to an explicit
<i><a href="aio_cancel.html">aio_cancel()</a></i>
request.

<dt>[EINVAL]<dd>
The file offset value implied by
<i>aiocbp-&gt;aio_offset</i>
would be invalid.

</dl>
<p>
The following condition may be detected synchronously or asynchronously:
<dl compact>

<dt>[EOVERFLOW]<dd>
The file is a regular file, 
<i>aiobcp-&gt;aio_nbytes</i>
is greater than 0 and the starting offset in
<i>aiobcp-&gt;aio_offset</i>
is before the end-of-file and is at or beyond the offset maximum in the
open file description associated with
<i>aiocbp-&gt;aio_fildes</i>.

</dl>
</blockquote><h4><a name = "tag_000_001_136">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_001_137">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_001_138">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_001_139">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="aio_cancel.html">aio_cancel()</a></i>,
<i><a href="aio_error.html">aio_error()</a></i>,
<i><a href="lio_listio.html">lio_listio()</a></i>,
<i><a href="aio_return.html">aio_return()</a></i>,
<i><a href="aio_write.html">aio_write()</a></i>,
<i><a href="close.html">close()</a></i>,
<i><a href="_exit.html">_exit()</a></i>,
<i><a href="exec.html">exec</a></i>,
<i><a href="fork.html">fork()</a></i>,
<i><a href="lseek.html">lseek()</a></i>,
<i><a href="read.html">read()</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995)  
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

